<ui:composition template="/WEB-INF/templates/showcase.xhtml"
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:o="http://omnifaces.org/ui"
	xmlns:demo="http://omnifaces.org/showcase"
>
	<ui:define name="description">
		<p>
			The <code>&lt;o:converter&gt;</code> basically extends the <code>&lt;f:converter&gt;</code> tag family with the
			possibility to evaluate EL in all attributes during view render time instead of during view build time. 
			This allows the developer to evaluate the attributes dynamically on a per request basis or even on a per
			iteration basis inside a repeater component.
		</p>
		<p>
			When you specify for example the standard <code>&lt;f:convertDateTime&gt;</code> by
			<code>converterId="javax.faces.DateTime"</code>, then you'll be able to use all its attributes such as
			<code>pattern</code> and <code>locale</code> as per 
			<a href="http://docs.oracle.com/javaee/6/javaserverfaces/2.1/docs/vdldocs/facelets/f/convertDateTime.html" rel="ext">its documentation</a>,
			but then with the possibility to supply render time value expressions.
		</p>
		<pre class="prettyprint"><code class="xhtml">
&lt;o:converter converterId="javax.faces.DateTime" pattern="\#{item.pattern}" locale="\#{item.locale}" /&gt;
		</code></pre>
		<p>
			The converter ID of all standard JSF converters can be found in 
			<a href="http://docs.oracle.com/javaee/6/api/javax/faces/convert/package-summary.html" rel="ext">their javadocs</a>.
			First go to the javadoc of the class of interest, then go to <code>CONVERTER_ID</code> in its field summary 
			and finally click the Constant Field Values link to see the value.
		</p>
		<p>
			In the below demo, it was the intent to use <code>&lt;f:convertDateTime&gt;</code> as follows:
		</p>
		<pre class="prettyprint"><code class="xhtml">
&lt;f:convertDateTime type="both" dateStyle="full" timeStyle="full" locale="\#{locale}" /&gt;
		</code></pre>
		<p>
			But this wouldn't even run, it will throw the following exception because the <code>\#{locale}</code> isn't 
			available during view build time (for a background explanation, check 
			<a href="http://stackoverflow.com/q/3342984/157882">this Stack Overflow answer</a>).
		</p>
		<pre>
javax.faces.view.facelets.TagAttributeException: /taghandlers/converter @62,92 
locale="#{locale}" Attribute did not evaluate to a String or Locale: null
    at com.sun.faces.facelets.tag.jsf.ComponentSupport.getLocale(ComponentSupport.java:297)
    at com.sun.faces.facelets.tag.jsf.core.ConvertDateTimeHandler.setAttributes(ConvertDateTimeHandler.java:127)
    at com.sun.faces.facelets.tag.jsf.ConverterTagHandlerDelegateImpl.applyAttachedObject(ConverterTagHandlerDelegateImpl.java:130)
		</pre>
		<p>
			It works as intuitively expected with the <code>&lt;o:converter&gt;</code> as it allows a render time evaluation of attributes.
		</p>
		<p>
			For another related use case, checkout the 
			<h:link outcome="validator"><code>&lt;o:validator&gt;</code> showcase page</h:link>.
		</p>
	</ui:define>

	<ui:define name="demo">
		<h:dataTable value="#{converterBean.locales}" var="locale">
			<h:column>
				<f:facet name="header">Language</f:facet>
				#{locale.displayLanguage}
			</h:column>
			<h:column>
				<f:facet name="header">Full date time pattern</f:facet>
				<h:outputText value="#{now}">
					<o:converter converterId="javax.faces.DateTime" type="both" dateStyle="full" timeStyle="full" locale="#{locale}" />
				</h:outputText>
			</h:column>
		</h:dataTable>
	</ui:define>
</ui:composition>